Note Allocator Functions: System Configuration and Utility 19

Use the functions in this section to create and maintain a database of music components, to save configuration information in the QuickTime Preferences file, to establish connections to external MIDI devices, and to allow the note allocator to perform necessary tasks at task foreground time.

NARegisterMusicDevice

The NARegisterMusicDevice function registers a music component with the note allocator.



 
pascal ComponentResult NARegisterMusicDevice( 

                     NoteAllocator na, 

                     OSType synthType, 

                     Str31 name,

                     SynthesizerConnections *connections);

na: You obtain the note allocator identifier from the Component Manager's OpenComponent function. See the chapter "Component Manager" in Inside Macintosh: More Macintosh Toolbox for details.
synthType: Subtype of the music component.
name: The synthesizer name.
*connections: A synthesizer connections for MIDI devices structure Synthesizer Connections for MIDI Devices .
function result: A result code.

DISCUSSION

The value of the synthType parameter is the music component's subtype. The name parameter provides a means of distinguishing multiple instances of the same type of device and is a string that can be displayed to the user. If no value is passed in the name parameter, the name defaults to the name of the music component type. The name appears in the instrument picker dialog.

The connections parameter specifies the hardware connections to the device.

RESULT CODES

`SynthesizerErr`	If too many synthesizers registered.
`midiManagerAbsentErr`	If MIDI not available.

NAUnregisterMusicDevice

The NAUnregisterMusicDevice function removes a previously registered music component from the note allocator.



 
pascal ComponentResult NAUnregisterMusicDevice( 

                     NoteAllocator na, 

                     long index;

na: You obtain the note allocator identifier from the Component Manager's OpenComponent function. See the chapter "Component Manager" in Inside Macintosh: More Macintosh Toolbox for details.
index: Synthesizer to unregister. The value is 1 through the registered music component count returned by the NAGetRegisteredMusicDevice function NAGetRegisteredMusicDevice .
function result: A result code. In addition to quickTime Music Architecture result codes, this function may return a result code from the CloseComponent function.

NAGetRegisteredMusicDevice

The NAGetRegisteredMusicDevice function returns specifics about music components registered to the specified note allocator instance.



 
pascal ComponentResult NAGetRegisteredMusicDevice( 

                     NoteAllocator na, 

                     long index,

                     OSType *synthType, 

                     Str31 name,

                     SynthesizerConnections *connections,

                     MusicComponent *mc);

na: You obtain the note allocator identifier from the Component Manager's OpenComponent function. See the chapter "Component Manager" in Inside Macintosh: More Macintosh Toolbox for details.
index: The index of the music component to get information about or 0 to get the total number of music components registered with the note allocator.
*synthType: Synthesizer type.
name: Synthesizer name as a text string.
*connections: A synthesizer connections for MIDI devices structure Synthesizer Connections for MIDI Devices .
*mc: Music component instance identifier.
function result: Positive values are the number of music components registered with the note allocator; negative values are result codes.

DISCUSSION

To get a count of the registered music components pass the NAGetRegisteredMusicDevice function 0 in the index parameter. The return value is the count of components. To get information about one of the music components registered with the note allocator, pass the music component index in the index parameter. The index value can be 1 through the number of registered components returned by a previous call to NAGetRegisteredMusicDevice .

If you request information about a specific registered music component, the NAGetRegisteredMusicDevice function returns the type of synthesizer the component supports in the synthType parameter, the name of the synthesizer in the name parameter, and the music component identifier in the mc parameter. For MIDI devices, it returns a pointer to a MIDI devices structure with information about the synthesizer connections.

NAGetDefaultMIDIInput

The NAGetDefaultMIDIInput function is used to obtain external MIDI connection information. This routine, in turn, calls the QT MIDI components to query them. NAGetMIDIPorts is the correct call for users to make. Users should not call QTMIDI .



 
pascal ComponentResult NAGetDefaultMIDIInput(

                     NoteAllocator na, 

                     SynthesizerConnections *sc);

na: You obtain the note allocator identifier from the Component Manager's OpenComponent function. See the chapter "Component Manager" in Inside Macintosh: More Macintosh Toolbox for details.
*sc: On exit, a synthesizer connections for MIDI devices structure Synthesizer Connections for MIDI Devices .

DISCUSSION

The NASGetDefaultMIDIInput function returns an initialized SynthesizerConnections structure containing information about the external MIDI device attached to the system that has been selected as the default MIDI input device. The external MIDI device provides note input directly to the note allocator.

function result: A result code.

NASetDefaultMIDIInput

The NASetDefaultMIDIInput function initializes an external MIDI device used to receive external note input.This routine, in turn, calls the QT MIDI components to query them. NAGetMIDIPorts is the correct call for users to make. Users should not call QTMIDI .



 
pascal ComponentResult NASetDefaultMIDIInput(

                     NoteAllocator na, 

                     SynthesizerConnections *sc);

na: You obtain the note allocator identifier from the Component Manager's OpenComponent function. See the chapter "Component Manager" in Inside Macintosh: More Macintosh Toolbox for details.
*sc: A synthesizer connections for MIDI devices structure Synthesizer Connections for MIDI Devices .

DISCUSSION

The SynthesizerConnections structure fields clientID , inputPortID, and outputPortID are MIDI Manager identifiers. The MIDIChannel field is the MIDI system channel value.

function result: A result code.

NAGetMIDIPorts

The NAGetMIDIPorts function gets the MIDI input and output ports available to a note allocator.This routine, in turn, calls the QT MIDI components to query them. NAGetMIDIPorts is the correct call for users to make. Users should not call QTMIDI .



 
extern pascal ComponentResult NAGetMIDIPorts(

                     NoteAllocator na,

                     Handle *inputPorts,

                     Handle *outputPorts)

na: You obtain the note allocator identifier from the Component Manager's OpenComponent function. See the chapter "Component Manager" in Inside Macintosh: More Macintosh Toolbox for details.
inputPorts: On exit, a handle giving the number of input ports (the first two bytes) followed by a list of QuickTime MIDI port structures QuickTime MIDI Port .
outputPorts: On exit, a handle giving the number of output ports (the first two bytes) followed by a list of QuickTime MIDI port structures QuickTime MIDI Port .
function result: A result code.

NASaveMusicConfiguration

The NASaveMusicConfiguration saves the current list of registered devices to a file.



 
pascal ComponentResult NASaveMusicConfiguration (NoteAllocator na);

na: You obtain the note allocator identifier from the Component Manager's OpenComponent function. See the chapter "Component Manager" in Inside Macintosh: More Macintosh Toolbox for details.

DISCUSSION

The NASaveMusicConfiguration saves the current list of registered devices to a file. This file is read whenever a note allocator connection is opened, restoring the previously configured list of devices. The list is saved in the QuickTime Preferences file.

function result: A result code or -1 if there is a problem opening or creating the QuickTime Preferences file.

NATask

Call the NATask function periodically to allow the note allocator to perform tasks in foreground task time.



 
extern pascal ComponentResult NATask (NoteAllocator na)

na: You obtain the note allocator identifier from the Component Manager's OpenComponent function. See the chapter "Component Manager" in Inside Macintosh: More Macintosh Toolbox for details.
function result: A result code.

DISCUSSION

The NATask function calls each registered music component's MusicTask function.